Battle Language Reference

Registers

Saga2edit uses the token rxx to represent the battle language's special efficient addressing mode for memory addresses of the form $cfxx. Most of this memory region (especially up to $cfdf) is only accessed via the battle language.

Registers are followed by a length specifier (unless there is no ambiguity); .b indicates a one-byte value, .w indicates the register and the next register reprenting a two-byte little endian value, and .l indicates the register and the following two registers representing a three-byte little endian value.

Labels

Labels can be made up of the 26 english letters (upper-case or lower-case), the digits from 0 to 9, the dot character, and the underscore character. Labels should not start with a digit or with a dot. Labels are translated into the resulting assembly file so they must also obey semantics of that assembler. A label is declared where it is followed by a colon.

-, --, +, ++ can also be used as un-named labels. The - labels are used for backwards jumps; the assembler will find the nearest matching label in the reverse direction. The + labels are similarly used for forwards jumps. These labels are translated to _minus_x, _minusminus_x, _plus_x, _plusplus_x, so these named are reserved. Labels of this kind must only be defined at the beginning of a line. (This prevents syntactic ambiguities as some of these tokens can also be used in expressions.)

Immediates

Some contexts require an immediate value or an address. In this context, a number can be written (in decimal, or, when prefixed with $, in hexadecimal). Or, a symbol can be given. A symbol will be treated as a 16-bit value that will be translated directly to the output. (This will generally be an address.) More complicated expressions can be translated to the output by enclosing them with curly braces {expression}. Such expressions require a length specifier when the length isn't entailed by the context.

Instructions

set

set rxx.b expr
set rxx.w expr
set rxx.l expr
set (rxx).b expr
set (rxx).w expr
set (addr).b expr
set (addr).w expr
set (addr).l expr

Evaluates the expression and stores the result in the indicated location. The result can be stored in a register (including variations for all three lengths), a memory address stored in (the two-byte version of) a register (available only in one-byte and two-byte versions), or in an fixed address. Each of these takes two bytes to encode (not counting the expression), except the immediate address version which takes three bytes.

if

if atom expr

The atom is used as the initial expression value (in other words, the initial contents of the accumulator). The expression is evaluated in conditional mode, and the resulting comparison is made. If the test succeeds, the next instruction is executed as normal. If the test fails, the next instruction is skipped. (An expression of any length can be skipped, even if it includes an arbitrarily long expression.)

goto

goto addr

Jumps to the indicated address.

asmcall

asmcall addr

Calls the given address as an assembly language function. (There is no firm protocol for marshaling data between battle language and assembly, but generally any necessary data is explicitly stored in memory outside the $cfxx region.)

call

call addr
call rxx

Calls the given address as a battle language function, or the address stored in the given (two-byte) register. There is no dedicated mechanism for parameters or return values.

return

return

Returns from the current call.

inc, dec

inc rxx.b
inc rxx.w
inc rxx.l
dec rxx.b
dec rxx.w
dec rxx.l

Increment or decrement the given register. Values will wrap gracefully.

exit

exit

Exit from battle language. This can be done from inside a call which can prevent a function call from returning.

Expressions

An expression is a sequence of op atom pairs. (The assembler requires that an expression has at least one such pair.) Each op (operator) is a binary operation which combines the accumulator with the corresponding atom. In comparison mode, some operators set the current value of the accumulator as the comparison value. The comparison will take place between the comparison value and the final value of the accumulator. The type of comparison is determined by this operator. The accumulator is a 24-bit value, and all logic is done with 24-bits except as noted. The first operator in a set instruction should not depend on the accumulator; (usually, this is =). Each operator takes one byte to encode. Atoms can take different numbers in byte to encode. Each expression also takes one extra byte to encode a terminator.

Note that the is no operator precedence. Operations are evaluated from left to right.

*

Multiplies the two values. This operates in 16-bit mode. The 24-bit sign is extracted from each value, then each value is truncated to 16 bits. The result of the multiplication is truncated to 16 bits, and then the appropriate 24-bit sign is reapplied.

/

Divides the accumulator by the atom. This operates in 16-bit mode analagous to multiplication.

+

Adds the two values.

-

Subtracts the atom from the accumulator.

--

Subtracts the atom from the accumulator. If the result would be less than zero, the result is zero instead.

&

Bitwise and of the two values.

|

Bitwise or of the two values.

^

Bitwise xor of the two values.

!&

Bitwise nand of the two values.

~

Bitwise complement of the atom. The accumulator is ignored.

>>

Left shift of the accumulator by the atom.

<<

Right shift of the accumulator by the atom.

<<

Right shift of the accumulator by the atom.

=

Takes the value of the atom, ignoring the accumulator. In comparison mode, introduces an equality comparison. Certain special atoms can used only with this operator.

<

Takes the value of the atom, ignoring the accumulator. In comparison mode, introduces a less than comparison.

>

Takes the value of the atom, ignoring the accumulator. In comparison mode, introduces a greater than comparison.

<=

Takes the value of the atom, ignoring the accumulator. In comparison mode, introduces a less-than-or-equal-to comparison.

>=

Takes the value of the atom, ignoring the accumulator. In comparison mode, introduces a greater-than-or-equal-to comparison.

Atoms

Immediate

x.b
x.w

Takes the value of the argument. If the length specifier is omitted, the smallest possible length will be used. An symbolic address (or external section) can also be used in this context. In this context, < can be used as a unary operator to take the lower byte of an address and > can take the upper byte.

Register

rxx.b
rxx.w
rxx.l

Takes the value of the register. This takes one byte to encode.

Register Address

(rxx).b
(rxx).w

Interpret the (16-bit) value of the register as an address and read the indicated number of bytes from that address. This takes one byte to encode.

Immediate Address

(addr).b
(addr).w
(addr).l

This is a special atom that can only be used with =. Read the indicated number of bytes from the given address. THis takes two byte to encode.

Register Random

rand rxx

This is a special atom that can only be used with =. Generates a random number between 0 and the value of the (one-byte) register (inclusive).

Immediate Random

rand x

Generates a random number between 0 and the given (one-byte) immediate value (inclusive). In this context, the immediate can only be a number, not a symbol.

Data Directives

.db x can be used to directly add a single byte value. .addr addr can be used to directly insert an address.

Comments

Comments are introduced by a semicolon and continue until the end of the line.

External Blocks

A block of code can be enclosed with double curly braces {{}}. This code will be translated directly to the assembly file.